<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
  <html xmlns="http://www.w3.org/1999/xhtml">
		<head>
			<!-- template designed by Marco Von Ballmoos -->
			<title>Docs For Class LoggerNDC</title>
			<link rel="stylesheet" href="../media/stylesheet.css" />
			<meta http-equiv='Content-Type' content='text/html; charset=iso-8859-1'/>
		</head>
		<body>
			<div class="page-body">			
<h2 class="class-name">Class LoggerNDC</h2>

<a name="sec-description"></a>
<div class="info-box">
	<div class="info-box-title">Description</div>
	<div class="nav-bar">
					<span class="disabled">Description</span> |
															<a href="#sec-method-summary">Methods</a> (<a href="#sec-methods">details</a>)
						
					</div>
	<div class="info-box-body">
        		<!-- ========== Info from phpDoc block ========= -->
<p class="short-description">The NDC class implements <em>nested diagnostic contexts</em> as defined by Neil Harrison in the article &quot;Patterns for Logging Diagnostic Messages&quot; part of the book &quot;<em>Pattern Languages of
 Program Design 3</em>&quot; edited by Martin et al.</p>
<p class="description"><p>A Nested Diagnostic Context, or NDC in short, is an instrument  to distinguish interleaved log output from different sources. Log  output is typically interleaved when a server handles multiple  clients near-simultaneously.</p><p>Interleaved log output can still be meaningful if each log entry  from different contexts had a distinctive stamp. This is where NDCs  come into play.</p><p><em>&lt;b&gt;Note that NDCs are managed on a per thread
 basis&lt;/b&gt;</em>. NDC operations such as <a href="../log4php/LoggerNDC.html#methodpush">push()</a>, <a href="../log4php/LoggerNDC.html#methodpop">pop()</a>,  <a href="../log4php/LoggerNDC.html#methodclear">clear()</a>, <a href="../log4php/LoggerNDC.html#methodgetDepth">getDepth()</a> and <a href="../log4php/LoggerNDC.html#methodsetMaxDepth">setMaxDepth()</a>  affect the NDC of the <em>current</em> thread only. NDCs of other  threads remain unaffected.</p><p>For example, a servlet can build a per client request NDC  consisting the clients host name and other information contained in  the the request. <em>Cookies</em> are another source of distinctive  information. To build an NDC one uses the <a href="../log4php/LoggerNDC.html#methodpush">push()</a>  operation.</p><p>Simply put,
<ul><li>Contexts can be nested.</li><li>When entering a context, call
   <div class="src-code"><ol><li><div class="src-line"><span class="src-id"><a href="../log4php/LoggerNDC.html">LoggerNDC</a></span><span class="src-sym">::</span><a href="../log4php/LoggerNDC.html#methodpush">push</a><span class="src-sym">(</span><span class="src-sym">)</span></div></li>
</ol></div>
   As a side effect, if there is no nested diagnostic context for the
   current thread, this method will create it.</li><li>When leaving a context, call
   <div class="src-code"><ol><li><div class="src-line"><span class="src-id"><a href="../log4php/LoggerNDC.html">LoggerNDC</a></span><span class="src-sym">::</span><a href="../log4php/LoggerNDC.html#methodpop">pop</a><span class="src-sym">(</span><span class="src-sym">)</span></div></li>
</ol></div></li><li><strong>When exiting a thread make sure to call <a href="../log4php/LoggerNDC.html#methodremove">remove()</a></strong></li></ul> There is no penalty for forgetting to match each  <div class="src-code"><ol><li><div class="src-line"><a href="../log4php/LoggerNDC.html#methodpush">push</a></div></li>
</ol></div> operation with a corresponding <div class="src-code"><ol><li><div class="src-line"><a href="../log4php/LoggerNDC.html#methodpop">pop</a></div></li>
</ol></div>,  except the obvious mismatch between the real application context  and the context set in the NDC.</p><p>If configured to do so, <a href="../log4php/layouts/LoggerPatternLayout.html">LoggerPatternLayout</a> and <a href="../log4php/layouts/LoggerLayoutTTCC.html">LoggerLayoutTTCC</a>  instances automatically retrieve the nested diagnostic  context for the current thread without any user intervention.  Hence, even if a servlet is serving multiple clients  simultaneously, the logs emanating from the same code (belonging to  the same category) can still be distinguished because each client  request will have a different NDC tag.</p><p></p></p>
	<ul class="tags">
				<li><span class="field">author:</span> Marco Vassura</li>
				<li><span class="field">version:</span> $Revision: 556784 $</li>
				<li><span class="field">since:</span> 0.3</li>
			</ul>
		<p class="notes">
			Located in <a class="field" href="_LoggerNDC.php.html">/LoggerNDC.php</a> (line <span class="field">91</span>)
		</p>
		
				
		<pre></pre>
	
			</div>
</div>




	<a name="sec-method-summary"></a>
	<div class="info-box">
		<div class="info-box-title">Method Summary</span></div>
		<div class="nav-bar">
			<a href="#sec-description">Description</a> |
												<span class="disabled">Methods</span> (<a href="#sec-methods">details</a>)
		</div>
		<div class="info-box-body">			
			<div class="method-summary">
												<div class="method-definition">
					static 						<span class="method-result">void</span>
										<a href="#clear" title="details" class="method-name">clear</a>
										()
									</div>
																<div class="method-definition">
					static 						<span class="method-result">array</span>
										<a href="#get" title="details" class="method-name">get</a>
										()
									</div>
																<div class="method-definition">
					static 						<span class="method-result">integer</span>
										<a href="#getDepth" title="details" class="method-name">getDepth</a>
										()
									</div>
																<div class="method-definition">
					static 						<span class="method-result">string</span>
										<a href="#peek" title="details" class="method-name">peek</a>
										()
									</div>
																<div class="method-definition">
					static 						<span class="method-result">string</span>
										<a href="#pop" title="details" class="method-name">pop</a>
										()
									</div>
																<div class="method-definition">
					static 						<span class="method-result">void</span>
										<a href="#push" title="details" class="method-name">push</a>
											(<span class="var-type">string</span>&nbsp;<span class="var-name">$message</span>)
									</div>
																<div class="method-definition">
					static 						<span class="method-result">void</span>
										<a href="#remove" title="details" class="method-name">remove</a>
										()
									</div>
																<div class="method-definition">
					static 						<span class="method-result">void</span>
										<a href="#setMaxDepth" title="details" class="method-name">setMaxDepth</a>
											(<span class="var-type">integer</span>&nbsp;<span class="var-name">$maxDepth</span>)
									</div>
								
																																																																				</div>
		</div>
	</div>		

	
	<a name="sec-methods"></a>
	<div class="info-box">
		<div class="info-box-title">Methods</div>
		<div class="nav-bar">
			<a href="#sec-description">Description</a> |
																<a href="#sec-method-summary">Methods</a> (<span class="disabled">details</span>)
						
		</div>
		<div class="info-box-body">
			<A NAME='method_detail'></A>
<a name="methodclear" id="clear"><!-- --></a>
<div class="oddrow">
	
	<div class="method-header">
		<span class="method-title">static method clear</span> (line <span class="line-number">103</span>)
	</div> 
	
	<!-- ========== Info from phpDoc block ========= -->
<p class="short-description">Clear any nested diagnostic information if any. This method is useful in cases where the same thread can be potentially used over and over in different unrelated contexts.</p>
<p class="description"><p>This method is equivalent to calling the <a href="../log4php/LoggerNDC.html#methodsetMaxDepth">setMaxDepth()</a>  method with a zero <var>maxDepth</var> argument.</p></p>
	<ul class="tags">
				<li><span class="field">access:</span> public</li>
			</ul>
	
	<div class="method-signature">
	    static
		<span class="method-result">void</span>
		<span class="method-name">
			clear
		</span>
				()
			</div>
	
		
			
	</div>
<a name="methodget" id="get"><!-- --></a>
<div class="evenrow">
	
	<div class="method-header">
		<span class="method-title">static method get</span> (line <span class="line-number">115</span>)
	</div> 
	
	<!-- ========== Info from phpDoc block ========= -->
<p class="short-description">Never use this method directly, use the <a href="../log4php/spi/LoggerLoggingEvent.html#methodgetNDC">LoggerLoggingEvent::getNDC()</a> method instead.</p>
	<ul class="tags">
				<li><span class="field">access:</span> public</li>
			</ul>
	
	<div class="method-signature">
	    static
		<span class="method-result">array</span>
		<span class="method-name">
			get
		</span>
				()
			</div>
	
		
			
	</div>
<a name="methodgetDepth" id="getDepth"><!-- --></a>
<div class="oddrow">
	
	<div class="method-header">
		<span class="method-title">static method getDepth</span> (line <span class="line-number">129</span>)
	</div> 
	
	<!-- ========== Info from phpDoc block ========= -->
<p class="short-description">Get the current nesting depth of this diagnostic context.</p>
	<ul class="tags">
				<li><span class="field">see:</span> <a href="../log4php/LoggerNDC.html#methodsetMaxDepth">LoggerNDC::setMaxDepth()</a></li>
				<li><span class="field">access:</span> public</li>
			</ul>
	
	<div class="method-signature">
	    static
		<span class="method-result">integer</span>
		<span class="method-name">
			getDepth
		</span>
				()
			</div>
	
		
			
	</div>
<a name="methodpeek" id="peek"><!-- --></a>
<div class="evenrow">
	
	<div class="method-header">
		<span class="method-title">static method peek</span> (line <span class="line-number">166</span>)
	</div> 
	
	<!-- ========== Info from phpDoc block ========= -->
<p class="short-description">Looks at the last diagnostic context at the top of this NDC without removing it.</p>
<p class="description"><p>The returned value is the value that was pushed last. If no  context is available, then the empty string &quot;&quot; is returned.</p></p>
	<ul class="tags">
				<li><span class="field">return:</span> The innermost diagnostic context.</li>
				<li><span class="field">access:</span> public</li>
			</ul>
	
	<div class="method-signature">
	    static
		<span class="method-result">string</span>
		<span class="method-name">
			peek
		</span>
				()
			</div>
	
		
			
	</div>
<a name="methodpop" id="pop"><!-- --></a>
<div class="oddrow">
	
	<div class="method-header">
		<span class="method-title">static method pop</span> (line <span class="line-number">146</span>)
	</div> 
	
	<!-- ========== Info from phpDoc block ========= -->
<p class="short-description">Clients should call this method before leaving a diagnostic context.</p>
<p class="description"><p>The returned value is the value that was pushed last. If no  context is available, then the empty string &quot;&quot; is returned.</p><p></p></p>
	<ul class="tags">
				<li><span class="field">return:</span> The innermost diagnostic context.</li>
				<li><span class="field">access:</span> public</li>
			</ul>
	
	<div class="method-signature">
	    static
		<span class="method-result">string</span>
		<span class="method-name">
			pop
		</span>
				()
			</div>
	
		
			
	</div>
<a name="methodpush" id="push"><!-- --></a>
<div class="evenrow">
	
	<div class="method-header">
		<span class="method-title">static method push</span> (line <span class="line-number">186</span>)
	</div> 
	
	<!-- ========== Info from phpDoc block ========= -->
<p class="short-description">Push new diagnostic context information for the current thread.</p>
<p class="description"><p>The contents of the <var>message</var> parameter is  determined solely by the client.</p></p>
	<ul class="tags">
				<li><span class="field">access:</span> public</li>
			</ul>
	
	<div class="method-signature">
	    static
		<span class="method-result">void</span>
		<span class="method-name">
			push
		</span>
					(<span class="var-type">string</span>&nbsp;<span class="var-name">$message</span>)
			</div>
	
			<ul class="parameters">
					<li>
				<span class="var-type">string</span>
				<span class="var-name">$message</span><span class="var-description">: The new diagnostic context information.</span>			</li>
				</ul>
		
			
	</div>
<a name="methodremove" id="remove"><!-- --></a>
<div class="oddrow">
	
	<div class="method-header">
		<span class="method-title">static method remove</span> (line <span class="line-number">197</span>)
	</div> 
	
	<!-- ========== Info from phpDoc block ========= -->
<p class="short-description">Remove the diagnostic context for this thread.</p>
	<ul class="tags">
				<li><span class="field">access:</span> public</li>
			</ul>
	
	<div class="method-signature">
	    static
		<span class="method-result">void</span>
		<span class="method-name">
			remove
		</span>
				()
			</div>
	
		
			
	</div>
<a name="methodsetMaxDepth" id="setMaxDepth"><!-- --></a>
<div class="evenrow">
	
	<div class="method-header">
		<span class="method-title">static method setMaxDepth</span> (line <span class="line-number">219</span>)
	</div> 
	
	<!-- ========== Info from phpDoc block ========= -->
<p class="short-description">Set maximum depth of this diagnostic context. If the current depth is smaller or equal to <var>maxDepth</var>, then no action is taken.</p>
<p class="description"><p>This method is a convenient alternative to multiple  <a href="../log4php/LoggerNDC.html#methodpop">pop()</a> calls. Moreover, it is often the case that at  the end of complex call sequences, the depth of the NDC is  unpredictable. The <a href="../log4php/LoggerNDC.html#methodsetMaxDepth">setMaxDepth()</a> method circumvents  this problem.</p></p>
	<ul class="tags">
				<li><span class="field">see:</span> <a href="../log4php/LoggerNDC.html#methodgetDepth">LoggerNDC::getDepth()</a></li>
				<li><span class="field">access:</span> public</li>
			</ul>
	
	<div class="method-signature">
	    static
		<span class="method-result">void</span>
		<span class="method-name">
			setMaxDepth
		</span>
					(<span class="var-type">integer</span>&nbsp;<span class="var-name">$maxDepth</span>)
			</div>
	
			<ul class="parameters">
					<li>
				<span class="var-type">integer</span>
				<span class="var-name">$maxDepth</span>			</li>
				</ul>
		
			
	</div>

						
		</div>
	</div>


	<p class="notes" id="credit">
		Documentation generated by <a href="http://www.phpdoc.org" target="_blank">phpDocumentor 1.3.2</a>
	</p>
	</div></body>
</html>